S j }™≥}™4}™• }™√ °T}}€ F €°T $B °T ¯ ™°T "ÿ N°T}™Δ ë ˘ + + + + + + + K d Ì ˜ § Ï € ¥ Å Ì Ç í 6 î ] S fl S õ } ÷ “ ÷ í ÷
S
E P ≤ Ì î > w ? w
· ] á ü – Ì • 4 ™ 4 ¯ Ì ° ä w ä ô - - 9 - E - T - l - § ä ª Ì ö u Ô Ô ∏ ◊ ≤ ◊ ê ◊ ë ◊ ◊ @ ◊ A ◊ h ◊ i ◊ — ◊ ’ º ◊ M W N W _ Õ z W ≠ d ˚ Ú – o ! o Q ê ≠ Ë Ì o Í ç † d % d & d ø K à ^ J K K
e Y f Z
à É m q ‰ Ê Î ˜
A ç
A ó
ô
ÿ
A §
º
| Ï
Ó ‹ € Ó Å Î Ç
5
6 à û ]
ê ^
*
;
*
F }
s Ø
Ñ ç
s ›
Ñ
s
*
E
F
Õ ≤
á › à û >
Ø ?
Ø
H
L
" á
à â
& ¬ •
–
6
O • Ó Í ® à æ ¯
6 °
Û v
w
é ∂
é –
é ô
9 §
Û ª
á ô
6 ö à z â
8 ∏
= ≤
ï ò
=
ï "
= :
ï ?
= i
ï p
=
ï •
= —
ï ı
= ’
º
= L Ù M å N Ó a _
3 y
Ü z Ó a ≠
Ö ˚ à ã ¬ Ó J –
Ó !
h "
E Q
3 S
fi x
3 ê
fi ÿ
Ò
3 ™
≠
3 Ë @ Ì r Í à è †
D
D #
D $ f d T}™x Tfi}™l 2´}}d æÁ}}l §)}}` ‹À}}\ Δ}}h §-}}X Ô˜}}@ kπ}}T T
›
T E C H N O T E :
Porting WinHelp to Apple Guide with Guide Maker
By Don Johnson
donjohn@apple.com
Apple Developer Technical Support (DTS)
If you are planning to port WinHelp source files to Apple Guide using the Apple Guide Maker development environment, there are some important issues that you need to address. This Technote discusses what you need to know in order to port your WinHelp files successfully.
The information in Apple Guide Complete, Chapter 8, is still accurate, but may be incomplete. For example, when the Guide Maker conversion program indicates that you have a successful conversion, you may just be, in fact, at the beginning of the process. This Technote provides you with the additional information you need to finish the process.
This Note is addressed to developers, technical writers, and instructional help fidesigners who need to convert WinHelp files to Apple Guide source files.
Using GuideMaker for Conversion
The only publicly-available tool for converting WinHelp to Apple Guide is Guide Maker, AppleÕs official development environment for creating guide files. You can find it in the Apple Guide section of the Mac OS SDK. Guide Maker converts the WinHelp source RTF files to Guide Script source RTF. There is some preparation required, however, for this to be successful.
Preparing the WinHelp Source RTF Files
The Guide Maker converter requires the WinHelp source files to be RTF (Rich Text Format) but does not use the XTND for translation (unlike the Guide Maker compiler which does use XTND for RTF and other formats). ´The converter reads the raw RTF directly and does a pattern match search for various items. This is one of the key problems with the converter because you can have several different variations of raw RTF text that mean the same thing. Unfortunately, the converter can only understand a few of these variations. The ÒsafestÓ variation is the RTF exported by Microsoft Word 4, which is what all of the test cases were taken from when the converter was written.
If the WinHelp source files are in RTF created by Word 6, there may be problems. Several RTF tags exported by Word 6 arenÕt understood and cause Guide Maker to crash. If you encounter this problem, convert the Word 6 RTF to an earlier RTF version. This can be done as follows:
1. Open the Word 6 WinHelp source RTF with Word 6. This will convert the RTF to ÒnormalÓ Word 6 format.
2. Using Word 6, save the WinHelp source as Word 5.1.
3. Using Word 5.1, open the Word 5.1 WinHelp source Á file.
4. Using Word 5.1, save the file as RTF.
You can also use Word 4 instead of Word 5.1.
On a Power Macintosh, you need to install the XTND Power Enabler in your Extensions folder. This is required by Guide Maker whether or not you are using any XTND translators. The XTND Power Enabler extension is available on the MAC OS SDK in the Guide Maker folder.
Be sure the WinHelp RTF source file type is ÔTEXTÕ. This allows Guide Maker to open the file for conversion.
Also refer to some other little ÒgotchasÓ on pages 8-3 to 8-4 of Apple Guide: Complete.
Using the Guide Maker Converted Output
The Guide Maker converter outputs its files in RTF. The first thing you should do is convert the RTF to )the native format of your favorite word processor or text editor. We do not recommend that you leave the output in RTF.
To convert the Guide Maker output from RTF, youÕll need a word processor that understands RTF or a word processor that uses XTND translation for RTF.
Microsoft Word is one example of a word processor that can read the Guide Maker RTF output directly. You can then save the file as ÒnormalÓ Word format or as ÒtextÓ.
If you elect to use a word processor that requires XTND for translation, then you will need to install XTND and a RTF translator.
Two RTF translators are currently available: one from Claris and one from DATAVIZ. If you have any Claris products installed, then you already have the Claris RTF translator. To be sure, check your Claris folder in your system folder for a À file named RTF. ThatÕs the file you need.
If you want to use the DATAVIZ translator, be sure to remove the Claris RTF translator from the system folder. The RTF translator from DATAVIZ comes free with the retail version of System 7.5. It is not included on the floppy version, just the CD-ROM version. This translator is installed separately from your system software installation. Users have reported that the DATAVIZ RTF translator is more robust than the Claris version.
Before you save the converted file, be sure it ends with one or more ÔreturnÕ characters. To be safe, go to the end of each file and enter a few return keys. Save the file in your favorite format or as ÒtextÓ.
Determining If the Translation Was Successful
To determine if your translation is successful, examine the Guide Script output after you have converted it from RTF. You can use a word processor or text editor for examining and editing the files.
If the conversion occurs properly, the resulting files will contain, for example, the following Apple Guide script commands:
To find the Guide Script commands, you need to search for the < character.
Steps to Fix the Converted File
Guide Maker does not perform the conversion, however, without a few errors. In the previous example, you need to fix the following the RTF conversion errors by hand:
The DATAVIZ RTF converter errors and fixes:
Error: <Define Panel> 5Panel 34"
The necessary fix: <Define Panel> "Panel 34"
Claris RTF converter errors and fixes:
Error: <Define Panel> µPanel 34"
The necessary fix: <Define Panel> "Panel 34"
The string following the <Define Panel> is the name of the panel and must be unique. You may need to invent new panel names when you make the fix.
After Conversion
Running the WinHelp files through the Guide Maker converter is only the first step to making a good Apple Guide file. ˜
Refer to the guideWorks web site <http://www.guideworks.com/> for the latest information on WinHelp conversion and a description of the complete conversion process.
Summary
Porting WinHelp source files to Apple Guide is, by and large, a straightforward conversion process. However, there some important steps you need to follow which arenÕt completely documented. This Technote tells you what you need to d πo in order to perform successful conversions.
Further References
The following references provide you with additional information on Apple Guide and the WinHelp conversion process.
¥ Apple Guide Complete by Apple Computer, Inc.
¥ The Apple Guide Internet mailing list. Send a message to: listserv@list.peter.com.au with the text "subscribe apple-guide Your Real Name" in the body.
¥ guideWorks Web Site. See the guideWorks web site for the latest information on Apple Guide including WinHelp conversion - <http://www.guideworks.com>
¥ AppleÕs Apple Guide Web page <http://www.macos.apple.com/Apple_Guide/>
Acknowledgments
Thanks to Tom Maremaa, Sunny Singha, Brian McGhie, and guideWorks, LLC.
Z ÿÿ N ° DSET ≠ ÿÿ . H
, ÿÿÿÿÿÿ}}ø ° √ Úf ˛ ¨ ° ÿÿ 6 ÿÿ * Úf ˛ DSET
ÿÿ . H X(P L*+ÿÿÿÿÿÿ}™| ˛ T ° ÿÿ √ Ü ° ÿÿ d ° ÿÿ ˘ ì ° ÿÿ
ÿÿÿÿ 7 l0 [ ] , ÿÿÿÿ 8 m0 [ ] , ÿÿÿÿ 9 n0 [ \ - ÿÿÿÿ : p0 [ \ - ÿÿÿÿ ; t0 [ _ + ÿÿÿÿ < v0 [ _ , ÿÿÿÿ % = y‹ ÿÿÿÿ ÿÿ > {0 y y . ÿÿÿÿ ? }0 y y ÿÿÿÿ @ ~0 y y ÿÿÿÿ A 0 y } / ÿÿÿÿ B •0 y } ÿÿÿÿ C ™0 y } ÿÿÿÿ D ≠0 y } ! ÿÿÿÿ E ∞0 y } " ÿÿÿÿ F ≥0 y } # ÿÿÿÿ G ∑0 y { 0 $
ÿÿÿÿ H ∫0 y { 0 %
ÿÿÿÿ I Ω0 y ~ & ÿÿÿÿ J √0 y ~ ' ÿÿÿÿ % K ≈‹ ÿÿÿÿ ( ÿÿ L …0 ≈ ≈ 1 ) ÿÿÿÿ M —0 ≈ ≈ * ÿÿÿÿ N ‘0 ≈ ≈ + ÿÿÿÿ O Ÿ0 ≈ — , ÿÿÿÿ P ⁄0 ≈ — - ÿÿÿÿ Q ∂0 ≈ — . ÿÿÿÿ R Δ0 ≈ — / ÿÿÿÿ S Œ0 ≈ — 0 ÿÿÿÿ T ‚0 ≈ — 1 ÿÿÿÿ U „0 ≈ … 2 6
ÿÿÿÿ ° ÿÿ ÿÿ œ ± ÿÿÿÿ ” ÿÿ ÿÿÿÿ “ ÿÿ /ÿÿÿÿ ´ " ÿÿ < 8ÿÿÿÿ µ & ÿÿ < 6ÿÿÿÿ ¶ 6 ÿÿ Ì < *ÿÿÿÿ · 8 ÿÿ Ô < 4ÿÿÿÿ ¸ = ÿÿ ◊ < =ÿÿÿÿ ’ D ÿÿ d < ÿÿÿÿ º W ÿÿ Iÿÿ ± » a W ÿÿÿÿ π o ÿÿ Jÿÿÿÿ ∏ r ÿÿ o Kÿÿÿÿ ≤ q U d = ÿÿÿÿ ¿ à ÿÿ C 6ÿÿÿÿ À á ÿÿ Ì C *ÿÿÿÿ Á ä ÿÿ Mÿÿÿÿ  é ÿÿ ä C Nÿÿÿÿ à | ÿÿ H
ÿÿÿÿ Ä 4 ÿÿ >ÿÿ » Å Í 4 ÿÿ « Æ æ
4 ! ÿÿÿÿ Ç - ?ÿÿÿÿ È 9 ÿÿ - C 4ÿÿÿÿ É Û ÿÿ ä C Aÿÿÿÿ Ê u ÿÿ :ÿÿ Æ Ë z
u ! ÿÿÿÿ Ì â ÿÿ u Oÿÿÿÿ Í ï ÿÿ ◊ C =ÿÿÿÿ Î ÿÿ ;ÿÿÿÿ Ï 3 ÿÿ C ÿÿ ‹ @ ÿÿ ÿÿ Ï Ñ Ö ÿÿ d C ÿÿÿÿ Ò E ÿÿ o Kÿÿ Ã Ó A ÿÿ C
ÿÿÿÿ Ô h ÿÿ o A Kÿÿÿÿ Õ O ÿÿ Ì G *ÿÿÿÿ Ö Q ÿÿ # ¢ ◊ Q ÿÿÿÿ Ø w ÿÿ Bÿÿÿÿ Ù Ø ÿÿ w C 8ÿÿÿÿ Ú S ÿÿ Fÿÿÿÿ Û ê ÿÿ S E *ÿÿÿÿ Ü Ü ÿÿ I ÿÿÿÿ † å W J ÿÿÿÿ fi ÷ ÿÿ Gÿÿÿÿ ß õ ÿÿ Cÿÿÿÿ à î ÿÿ Hÿÿ Ë á û
î ! ÿÿÿÿ â ÿÿ Rÿÿ € ã ÿÿ *ÿÿÿÿ ä ÿÿ ä E Aÿÿÿÿ å ÿÿ ◊ G =ÿÿÿÿ æ ÿÿ Vÿÿÿÿ ç ÿÿ C Wÿÿÿÿ è Ó ÿÿ o C Kÿÿÿÿ é fi ÿÿ ? ÿÿÿÿ ê ÿÿ E ÿÿÿÿ ë í ÿÿ Sÿÿÿÿ ì ÿÿ í E Tÿÿÿÿ í ÿÿ S Pÿÿ Å î J Ú ÿÿÿÿ ï ÿÿ í C Tÿÿ À › * ÿÿ S C *ÿÿÿÿ ñ ; ÿÿ S *ÿÿÿÿ ò F ÿÿ õ C Lÿÿÿÿ ó s ÿÿ ÷ C Qÿÿÿÿ ô Ñ ÿÿ ÷ C Eÿÿ › õ Õ ÿÿ C *ÿÿÿÿ ö ›
RULR}z Æÿÿ ÿ ÿÿ ) ÿ ÿÿ ‡ @ ÿÿ \ ÿÿ $ ÿÿ ÿ @ ÿÿ $ ÿÿ $ ÿÿ íó b B N . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ ÿÿ ÿ  B ÿÿ $ ÿÿ H ÿÿ ÿ b B N . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ l ÿÿ Δ ÿÿ ÿ b B ÿÿ ´ ÿÿ Ø ÿÿ ÿ  B d ÿÿ eû ˚ ÿÿ ü ÿÿ i÷  B ÿÿ ÿÿ D ÿÿ mó b B N . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ h ÿÿ i÷ b B ÿÿ
‘ ÿÿ ° ÿÿ ÿÿ $ ÿÿ H ÿÿ l ÿÿ Δ ÿÿ ´ ÿÿ í÷ bÿæ B N . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ Ø ÿÿ ü ÿÿ ÿÿ D ÿÿ h ÿÿ ÿ bÿæ B N . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ ÿÿ $ ÿÿ H ÿÿ l ÿÿ íó bÿÿ B N . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ Δ ÿÿ ´ ÿÿ i÷ ˚ B ÿÿ ÷ B ÿÿ ÿ B ÿÿ h÷ B ÿÿ ÿ b B N . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ iÿ  B d ÿÿ ÿ bÿÿ B N . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ <ÿÿÿÿ ÿ ˚ ÿÿ íò z B N . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ iÿ b B Uÿÿÿÿ éö z B N . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ ÿ B ÿÿ áfl ¢ N . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ ÿ B ÿÿ i÷ z B ÿÿ ÿ b B N . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ íÿ bÿÿ B N . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ m2 bÿõ e Q . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ i÷ j B ÿÿ bÿõ e Q . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ íz bÿæ B N . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ m bÿõ e Q . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ mÿ z B ÿÿ aÿ ˚ ÿÿ íó b B N . j . } . Δ . £ . ¶ . Ê . † . › . . .* .= .P .c .v .… .ˇ .°˛˚¶˛ÿÿ ÿ b B N . j . } . Δ . £ . ¶ . Ê . † . › . . .* .= .P .c .v .… .ˇ .°˛˚¶˛ÿÿ ÿ bÿõ e ÿÿ i÷ b B N . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ ÿ b B ÿÿ ÿ z B N . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ ÿ b B ÿÿ ÿ bÿõ e ÿÿ íÿ bÿæ B N . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ é~ b B N . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿ ÿ b B N . ˛˜›Δ°˛˚¶˛˚¶˛˜üΔ[Ú˛˚¶˛˘ΔpT˛˚¶∂ôV˛˘ΔX˛˘ Δ˛˘,Δ°˛˚¶˛ÿÿÿÿÿÿ ÿ bÿô x ÿÿ i· b B ÿÿ ÿ b B Uÿÿ HASH ÿ Bÿ 4 D = J÷ 3 Jÿ ? œ W œ ¬ù 5 Êö Q
’ Vù ;o
ù ÿ +, ,0 Q -v .˝ 0À 10 ‡
I fl , G ù 2Q v ˝ œ Nœ PÀ Êö Lå
+ H/ T y ı Ã , Q v !˝ "À #å %
& / ' T ( y )
0 •`î K m`â Jù D'ù @ €N E Mƒ G#•T‰ A#•T 6#™T‰ T#™T
